Graphics Plus

home *** CD-ROM | disk | FTP | other *** search

/ Graphics Plus / Graphics Plus.iso / msdos / animutil / fastgfx / fg303b / manuals.arj / USERAPP.DOC < prev

Wrap

Text File | 1993-10-02 | 61.1 KB | 1,330 lines

Appendix A Fastgraph Utilities 310 Fastgraph User's Guide Overview This appendix describes the utility programs supplied with Fastgraph. By default, the Fastgraph installation procedure places these utilities in the \FG directory. To use these utilities, you must either (1) copy the .EXE file from \FG to your current directory, (2) make \FG your current directory, or (3) include the \FG directory in your DOS path specification. SNAPSHOT Utility The SNAPSHOT utility is a terminate and stay resident program (TSR) to capture graphic images. It stores the image in Fastgraph's standard pixel run format. To load SNAPSHOT, just enter the command SNAPSHOT at the DOS prompt, and you'll see messages similar to the following if SNAPSHOT loads successfully. C> SNAPSHOT SNAPSHOT Version 1.02 Copyright (c) 1991 Ted Gruber Software. All Rights Reserved. Press <alt>-<left shift> to activate. After SNAPSHOT loads, control returns to the DOS prompt. At this point, you can use any method whatsoever to display a graphic image and then press the Alt and left shift keys at the same time to capture the image. You don't need to load SNAPSHOT for each image capture, just once per system boot. SNAPSHOT uses about 14,000 bytes of conventional memory once loaded. To illustrate the use of SNAPSHOT, suppose you have drawn and saved an image with a commercial paint program, and you want to incorporate this image into a Fastgraph application. Once you load SNAPSHOT, start the paint program and retrieve your image. Then press the Alt and left shift keys simultaneously and wait for the success tone (three quick medium-pitched sounds). Finally, exit the paint program to return to the DOS prompt. The sequence described in the preceding paragraph will store the captured image in Fastgraph's standard pixel run format, in a file named SNAPSHOT.nnn in the current directory. The file type nnn will be the first sequence of digits that does not result in a duplicate file name. That is, if there are no captured image files in the current directory, SNAPSHOT will use the file name SNAPSHOT.000. The next time you capture an image, SNAPSHOT will store it in SNAPSHOT.001, then SNAPSHOT.002, and so forth. If you rename or delete one of these files, SNAPSHOT will again use that file name. For example, if you delete SNAPSHOT.000 but keep SNAPSHOT.001, SNAPSHOT will store the next image it captures in SNAPSHOT.000. If SNAPSHOT is unable to capture the image, it will produce its error tone (a single low-pitched sound). The most common cause of this is trying to capture an image from a text video mode, but it also will occur if there is not enough disk space or if all 1,000 image file names are already being used. Appendix A: Fastgraph Utilities 311 CLIP Utility The SNAPSHOT utility described in the previous section captures the entire screen. While this might be desirable in some cases, other times you'll just need a portion of the screen. CLIP is an interactive utility that you can use to reduce the size of any image stored in Fastgraph's standard or packed pixel run format. The syntax of the command for invoking the CLIP utility from the DOS prompt is CLIP input_file output_file options where input_file is the name of the original image file, and output_file is the name of the new image file. CLIP does not modify the input_file in any way, but it will overwrite the output_file if an identically named file exists in the current directory. The options list specifies one or more optional switches as shown below. option meaning /M:mode Specifies the video mode number in which to display the image. The mode value must be an integer between 0 and 29. If that video mode is a text mode, an unsupported graphics mode, or an unavailable graphics mode, CLIP displays an error message stating this. If the /M switch is not present, CLIP uses the first available video mode from the list 18, 16, 15, 19, 13, 9, 4, 12. /P Indicates the input_file is in Fastgraph's packed pixel run format. If the /P switch is not present, CLIP assumes it is in standard pixel run format. The output_file will be in the same format as the input_file. /W:width Specifies the image width in pixels. The width value must be an integer between 1 and the horizontal resolution of the selected video mode. If the /W switch is not present, CLIP uses the horizontal resolution of the selected video mode. For example, if you wanted to create the image file PARTIAL.PPR from the packed pixel run file SCREEN.PPR, and use the native 320 by 200 EGA graphics video mode (mode 13), you would start CLIP with the following command. CLIP PARTIAL.PPR SCREEN.PPR /P /M:13 Because no /W switch appears in the above command and the horizontal resolution of mode 13 is 320 pixels, CLIP assumes the image width is 320 pixels. When CLIP displays the image and the plus-shaped cursor, you are ready to define one corner of the clipping region (that part of the image used to create the output_file). To do this, use the directional keys on the numeric keypad to move the cursor to the desired position, then press the Enter key. You are then ready to define the clipping region's opposite corner. Again, use the directional keys to move the cursor to the desired position. When defining the second corner, however, CLIP uses a rectangular box instead of the plus-shaped cursor to simplify marking the clipping region's boundaries. After you press Enter to define the second corner, CLIP creates the 312 Fastgraph User's Guide output_file and displays the resulting image width and the number of pixel runs the image contains. CLIP includes some features that may help you define the clipping region. You can change the distance the cursor moves in response to the directional keys, display the current (x,y) pixel coordinates of the cursor, and change the cursor color. The following table explains the keystrokes that CLIP recognizes when you are defining the clipping region. key meaning F1 Displays the (x,y) coordinate bar at the top of the screen. If the coordinate bar is already on, F1 removes it. F2 Displays the (x,y) coordinate bar at the bottom of the screen. If the coordinate bar is already on, F2 removes it. F3 Changes the cursor or box color from white to black, or from black to white. F4 Displays a summary of the keys CLIP recognizes when defining the clipping region. KP1 Moves the cursor one unit down and to the left. KP2 Moves the cursor one unit down. KP3 Moves the cursor one unit down and to the right. KP4 Moves the cursor one unit to the left. KP6 Moves the cursor one unit to the right. KP7 Moves the cursor one unit up and to the left. KP8 Moves the cursor one unit up. KP9 Moves the cursor one unit up and to the right. + Increases the unit of cursor movement by one pixel. The default cursor movement is one pixel. - Decreases the unit of cursor movement by one pixel. Enter Defines a corner of the clipping region at the cursor position. Esc Exits to DOS without creating the output_file. CLIP will first issue an "Exit to DOS?" prompt in case you pressed the Esc key accidentally. CONVERT Utility The CONVERT utility lets you translate files between Fastgraph's SPR and PPR image file formats. The syntax of the command for invoking CONVERT from the DOS prompt is CONVERT input_file output_file where input_file is the name of the original image file, and output_file is the name of the new translated image file. CONVERT does not modify the input_file in any way, but it will overwrite the output_file if an identically named file exists in the current directory. By default, the file type of the input_file and output_file determine the image format of that file. If the file type is .PPR, CONVERT assumes the image is in Fastgraph's packed pixel run format. If the file type is .SPR, CONVERT assumes it is in the Fastgraph's standard pixel run format. If your image files use other file types, you can explicitly specify the file's image format by appending one of the switches /PPR or /SPR to the file name. The Appendix A: Fastgraph Utilities 313 input_file and output_file must not both specify the same image format (CONVERT will display an error message if this is so). The following command will translate the standard pixel run file PICTURE.SPR to packed format. The packed image will be stored in the file PICTURE.IMG, so we must append the switch /PPR to tell CONVERT that it will be a packed file. CONVERT PICTURE.SPR PICTURE.IMG/PPR EDITSPR Utility The EDITSPR utility changes all pixel runs of one color to another color in an image file stored in Fastgraph's standard pixel run (SPR) format. The syntax of the command for invoking the EDITSPR utility from the DOS command prompt is EDITSPR input_file output_file where input_file is the name of the original image file, and output_file is the name of the new image file. EDITSPR does not modify the input_file in any way, but it will overwrite the output_file if an identically named file exists in the current directory. After it reads the pixel runs from the input_file, EDITSPR will perform the requested color changes. It does this iteratively by asking for an old color value followed by a new color value (each value must be between 0 and 255). EDITSPR then finds the pixel runs of the old color value and changes them to the new color value. Following this, EDITSPR displays a message stating how many pixel runs it changed. This process repeats until you enter a negative number for either color value. EDITSPR will next combine adjacent pixel runs of like colors. For example, suppose the original image file contained a color 1 pixel run of length 50, followed by a color 2 pixel run of length 20, followed by another color 1 pixel run of length 10. If you changed all color 2 pixel runs to color 1, EDITSPR will combine these three pixel runs into a single run of length 80. Finally, EDITSPR will close the output_file. GrabRGB Utility The GrabRGB utility is a terminate and stay resident program (TSR) to capture the current red, green, and blue color components of video DAC registers in 256-color graphics modes. You can use GrabRGB together with Fastgraph's SNAPSHOT utility to preserve the original colors of a captured image. To load GrabRGB, just enter the command GRABRGB at the DOS prompt. After GrabRGB loads, control returns to the DOS prompt. At this point, you can use any method whatsoever to display a 256-color graphic image and then press the Alt and right shift keys at the same time to capture the current DAC values. You don't need to load GrabRGB for each image, just once per 314 Fastgraph User's Guide system boot. GrabRGB uses about 15,000 bytes of conventional memory once loaded. To illustrate the use of GrabRGB, suppose you have drawn and saved a 256-color image with a commercial paint program, and you want to incorporate this image into a Fastgraph application. Once you load SNAPSHOT and GrabRGB, start the paint program and retrieve your image. Then press the Alt and left shift keys to capture the image with SNAPSHOT. After SNAPSHOT's success tone (three quick medium-pitched sounds), press Alt and right shift to capture the RGB components of each DAC register with GrabRGB, and wait for GrabRGB's success tone. Finally, exit the paint program and return to the DOS prompt. The sequence described in the preceding paragraph will write the RGB color components for each DAC register to a file named GRABRGB.nnn in the current directory. The file type nnn will be the first sequence of digits that does not result in a duplicate file name. That is, if there are no GrabRGB output files in the current directory, GrabRGB will use the file name GRABRGB.000. The next time you use GrabRGB, it will store the RGB information in GRABRGB.001, then GRABRGB.002, and so forth. If you rename or delete one of these files, GrabRGB will again use that file name. For example, if you delete GRABRGB.000 but keep GRABRGB.001, GrabRGB will next use the file name GRABRGB.000. If GrabRGB is unable to obtain the RGB components of each DAC register, it will produce its error tone (a single low-pitched sound). The most common cause of this is trying to capture an image from a text video mode, or from a graphics video mode with fewer than 256 colors. It also will occur if there is not enough disk space or if all 1,000 output file names are already being used. Each line in the output file created by GrabRGB is of the form nnn,rr,gg,bb, where nnn is a DAC register index (between 0 and 255), rr is the red component of that DAC register, gg is the green component, and bb is the blue component. Each color component is between 0 and 63. You can edit and reformat these lines as necessary for inclusion in a C initializer list, a BASIC or FORTRAN data statement, or a Pascal array-type constant list. Such an array of RGB components, but without the nnn indices, is in the format expected by fg_setdacs. By default, GrabRGB captures information for all 256 DAC registers. If you want to consider only the DAC registers with color components different from their initial values, just include the /D option when you load GrabRGB (that is, use the command GRABRGB /D). If you specify the /D option and all 256 DACs use their default values, the output file will contain a message stating this. HERCFIX Utility The HERCFIX utility allows you to use SNAPSHOT (and possibly other TSRs) with programs that do not update the BIOS data area when establishing the 720 by 348 Hercules graphics mode. If you use SNAPSHOT with such a program, it will think the monochrome text mode (video mode 7) is active and will produce its low-pitched error tone when activated. Appendix A: Fastgraph Utilities 315 If this occurs, use HERCFIX to load the application from which you are trying to capture the image. To do this, enter HERCFIX command at the DOS prompt, where command is the command that starts the application. For example, suppose you use the command PAINTER /H to run a commercial paint program in Hercules graphics mode. To load the paint program with HERCFIX, you would enter the command HERCFIX PAINTER /H. PCXHEAD Utility The PCXHEAD utility displays the most important information from the header of a PCX file. This consists of the PCX version number, the number of bits per pixel, the number of bit planes, the scan line width, and the image dimensions and screen position. It also proposes the optimal video mode for displaying the PCX file. By optimal, we mean the compatible video mode having the lowest resolution larger than or equal to the image dimensions. For 256-color PCX images, PCXHEAD displays the extended color palette if one is present. The syntax of the command for invoking the PCXHEAD utility from the DOS command prompt is PCXHEAD pcx_file where pcx_file is the name of the PCX file to examine. PCXHEAD does not modify the pcx_file in any way. If the PCX file includes an extended color palette, you may prefer to direct the PCXHEAD output to a file using the DOS redirection operator (>). 316 Fastgraph User's Guide Appendix B Using Fastgraph from Assembly Language 318 Fastgraph User's Guide Fastgraph uses the same naming and calling conventions as Microsoft C and Turbo C. The details of these conventions that are important to assembly language programming are summarized below. If you are calling Fastgraph routines from an assembly language program, the program must follow these conventions. All arrays and pointers are passed by reference All other items are passed by value Arguments are pushed onto the stack in reverse order 16-bit function values are returned in the AX register 32-bit function values are returned in the DX:AX register pair Fastgraph routine names are prefixed with an underscore The small and medium model Fastgraph libraries pass arrays and pointers by near reference, while the large model library does so by far reference. This is consistent with the run-time libraries for the supported compilers. All Fastgraph routines preserve the BP, DS, DI, and SI registers. The contents of any other registers are unknown upon return from a Fastgraph routine (except for the AX register, which will either contain zero or the routine's return value). The following DOS commands show how to assemble a program (using the Microsoft Macro Assembler) and then link it with Fastgraph. In all cases, we'll assume the file EXAMPLE.ASM contains the source code for the program. The resulting executable file will be called EXAMPLE.EXE. small memory model MASM EXAMPLE.ASM; LINK /CP:4096 /E EXAMPLE,,NUL.MAP,FGS medium memory model MASM EXAMPLE.ASM; LINK /CP:4096 /E EXAMPLE,,NUL.MAP,FGM large memory model MASM EXAMPLE.ASM; LINK /CP:4096 /E EXAMPLE,,NUL.MAP,FGL Example B-1 calls the fg_getmode, fg_setmode, fg_reset, and fg_version routines from an assembly language program. The fg_getmode routine returns its function value in the AX register. The fg_setmode routine has a single argument, while fg_reset has no arguments. The fg_version routine has two arguments, both passed by reference. Notice how they are pushed on the stack in reverse order. This example would work with either the medium or large memory model Fastgraph libraries. To make it work with the small model library, all you would need to do is change the word "far" to "near" in the EXTRN declarations, and change the name of the code segment from "main_TEXT" to "_TEXT". Appendix B: Using Fastgraph from Assembly Language 319 Example B-1. EXTRN _fg_getmode:far ; Fastgraph's GETMODE routine EXTRN _fg_reset:far ; Fastgraph's RESET routine EXTRN _fg_setmode:far ; Fastgraph's SETMODE routine EXTRN _fg_version:far ; Fastgraph's VERSION routine stackseg SEGMENT stack ; suppress the linker's stackseg ENDS ; "no stack segment" error message _DATA SEGMENT word public 'DATA' major dw ? ; major version number minor dw ? ; minor version number old_mode dw ? ; original video mode _DATA ENDS dgroup GROUP _DATA ASSUME cs:main_TEXT,ds:dgroup main_TEXT SEGMENT byte public 'CODE' start: mov ax,_DATA ; load segment location mov ds,ax ; into DS register call _fg_getmode ; AX = current video mode mov old_mode,ax ; save it mov ax,4 ; use video mode 4 push ax ; pass argument to SETMODE call _fg_setmode ; establish CGA four-color mode add sp,2 ; remove SETMODE argument push old_mode ; pass argument to SETMODE call _fg_setmode ; restore original video mode add sp,2 ; remove SETMODE argument call _fg_reset ; restore screen attributes lea ax,minor ; get address of minor variable push ax ; pass argument #2 to VERSION lea ax,major ; get address of major variable push ax ; pass argument #1 to VERSION call _fg_version ; get the Fastgraph version number add sp,4 ; remove VERSION arguments mov ah,76 ; function 76: terminate process xor al,al ; errorlevel 0 int 21h ; exit to DOS main_TEXT ENDS END start 320 Fastgraph User's Guide Appendix C Interrupts and Fastgraph 322 Fastgraph User's Guide Interrupts Used by Fastgraph DOS maintains an interrupt vector table that contains the addresses of 256 interrupt handlers, or routines, that perform various functions. The handlers are usually referenced by their hexadecimal interrupt number, between 00 and FF. Of these, only interrupts 60 through 66 and F1 through FF are not used by DOS, the ROM BIOS, or other software and are thus available for user applications. Certain Fastgraph routines use some of the available interrupts. Namely, the fg_music routine uses interrupt 60, the asynchronous sound routines (fg_musicb, fg_sounds, and fg_voices) use interrupts 60 and 61, and all Fastgraph/Light routines use interrupt 62. If your program defines its own interrupt handlers, it must not use any of the interrupts reserved for Fastgraph (unless, of course, it doesn't use any of the Fastgraph routines that would create a conflict). Extending the Time-of-Day Interrupt As mentioned in Chapter 16, the BIOS time-of-day clock is incremented by an interrupt handler. The routine that does this is interrupt 08, a hardware interrupt automatically activated 18.2 times per second. After incrementing the clock, interrupt 08 invokes interrupt 1C, which by default references a "do-nothing" interrupt handler. While changing interrupt 08 can be tricky, it is fairly straightforward to define our own handler for interrupt 1C. This handler also will be executed automatically 18.2 times per second. Example C-1 illustrates how to do this. When we discussed joysticks in Chapter 14, we said there were two ways to monitor joystick button status. One is to intersperse calls to the fg_button routine at strategic places in your program and then take necessary action depending on the button status. However, the problem with this scheme is the chance of missing a button press -- if you press the joystick button and then release it between calls to fg_button, the program will not detect the joystick activity. A preferable method is to call fg_button from a handler for interrupt 1C, which essentially provides continuous monitoring of the joystick buttons. When we need the button status within our program, all we need to do is examine a global variable. Example C-1 consists of a main program (written in C) and an assembly language subroutine named int1C (suitable for the medium memory model). The main program calls int1C to define a handler for interrupt 1C. In response to any keystroke (except Escape), the program displays the button press information for each joystick since the previous keystroke (refer to the discussion of the fg_button routine for the meanings of the status values). When you press the Escape key, the program exits to DOS, but not before calling int1C to restore the original interrupt 1C handler. Example C-1 (main program). #include <fastgraf.h> #include <stdio.h> void main(void); #define ESC 27 Appendix C: Interrupts and Fastgraph 323 int status1, status2; void main() { unsigned char key, aux; int1C(1); status1 = 0; status2 = 0; do { printf("\n"); printf("Joystick 1 status: %d\n",status1); printf("Joystick 2 status: %d\n",status2); status1 = 0; status2 = 0; fg_getkey(&key,&aux); } while (key != ESC); int1C(0); } We'll now examine the int1C assembly language subroutine. It actually consists of three parts: a portion to enable our interrupt handler, our handler itself, and a portion to disable the handler. When we call int1C with a nonzero argument, it saves the original data segment (so we can access the global variables within the handler), saves the original handler's address (called the vector) for interrupt 1C, and then enables our handler, which takes the form of a far procedure. The handler routine then begins to be activated at 18.2 times per second. After saving all the important registers, the handler calls the Fastgraph routine fg_button twice, once for each joystick. The return values are logically ORed with the status1 and status2 C global variables to update the button status information. Finally, the handler restores the original registers and returns control to the point of the interrupt. Before the main program exits, it calls int1C with a zero argument to restore the original handler for interrupt 1C. No provision is made in the program to check if we had previously defined our own handler (and hence saved the original interrupt 1C vector), but this could be added with little difficulty. Example C-1 (assembly language subroutine). EXTRN _status1:word ; C global variable for button 1 status EXTRN _status2:word ; C global variable for button 2 status EXTRN _fg_button:far ; Fastgraph routine 324 Fastgraph User's Guide int1C_TEXT SEGMENT byte public 'CODE' ASSUME cs:int1C_TEXT int1C_CS dw ? ; holds original INT 1C segment address int1C_IP dw ? ; holds original INT 1C offset orig_DS dw ? ; holds original data segment _int1C PROC far PUBLIC _int1C push bp ; save caller's BP register mov bp,sp ; make BP point to argument list push si ; save caller's SI register push di ; save caller's DI register mov dx,[bp+6] ; get the flag parameter or dx,dx ; replace the old interrupt handler? jz replace ; yes, branch to that processing ; define a new handler for INT 1C define: mov ax,ds ; put current data segment in AX mov cs:orig_DS,ax ; save it in the control information area mov al,1Ch ; interrupt vector to save mov ah,53 ; function 53: get interrupt vector int 21h ; get the interrupt vector Appendix C: Interrupts and Fastgraph 325 mov cs:int1C_CS,es; save the segment mov cs:int1C_IP,bx; save the offset push ds ; save our DS register mov dx,offset handler ; get offset of interrupt handler mov ax,seg handler; get segment of interrupt handler mov ds,ax ; put it in DS mov al,1Ch ; interrupt vector to change mov ah,37 ; function 37: set interrupt vector int 21h ; change the INT 1C vector to our handler pop ds ; restore our DS register jmp short return ; return to the caller ; replace the original handler for INT 1C replace: push ds ; save our DS register mov dx,cs:int1C_IP; put original INT 1C offset in DX mov ds,cs:int1C_CS; put original INT 1C segment in DS mov ah,37 ; function 37: set interrupt vector mov al,1Ch ; interrupt vector 1C int 21h ; restore original INT 1C vector pop ds ; restore our DS register return: xor ax,ax ; in case int1C was called as a function pop di ; restore our DI register pop si ; restore our SI register pop bp ; restore our BP register 326 Fastgraph User's Guide ret _int1C ENDP handler PROC far ; interrupt handler that replaces INT 1C cli ; disable interrupts while handler active push ax ; save registers that may be altered push bx push cx push dx push di push si push ds push es mov ds,cs:orig_DS ; retrieve the original data segment mov ax,1 ; use joystick 1 push ax ; pass joystick number to button routine call _fg_button ; AX = button status for joystick 1 add sp,2 ; remove the argument or _status1,ax ; update status variable for joystick 1 mov ax,2 ; use joystick 2 push ax ; pass joystick number to button routine call _fg_button ; AX = button status for joystick 2 Appendix C: Interrupts and Fastgraph 327 add sp,2 ; remove the argument or _status2,ax ; update status variable for joystick 2 pop es ; restore altered registers pop ds pop si pop di pop dx pop cx pop bx pop ax iret ; return from the interrupt routine handler ENDP int1C_TEXT ENDS END The example just presented is not meant to be a tutorial on interrupts; there are many good references on DOS that explain them in detail. However, an example specific to Fastgraph should be helpful. 328 Fastgraph User's Guide Appendix D Contents of the Compiler-Specific Libraries 330 Fastgraph User's Guide Each supported Fastgraph compiler except QuickBASIC and Visual Basic for DOS have a compiler-specific Fastgraph library (also called the extended Fastgraph library) that contains the following routines: fg_boxw fg_drawxw fg_panw fg_setsize fg_boxxw fg_drectw fg_pointw fg_setsizew fg_circlew fg_ellipsew fg_pointxw fg_setworld fg_circlefw fg_ellipsfw fg_polygonw fg_swchar fg_clprectw fg_floodw fg_rectw fg_swlength fg_dashrw fg_getworld fg_restorew fg_swtext fg_dashw fg_initw fg_savew fg_xscreen fg_drawrw fg_moverw fg_setangle fg_xworld fg_drawrxw fg_movew fg_setclipw fg_yscreen fg_draww fg_paintw fg_setratio fg_yworld These routines use the world space coordinate system, either directly or internally. Note that none of them are included in Fastgraph/Light. As mentioned in Chapter 1, if your program uses any of these routines, you must link it with the standard Fastgraph library and the corresponding extended Fastgraph library. Appendix E Contents of the Pascal Unit Files 332 Fastgraph User's Guide Borland Pascal and Turbo Pascal restrict the total size of all code segments in a unit file 65,520 bytes. Because the size of Fastgraph's code exceeds this amount, the Fastgraph functions are split among several unit files. This appendix lists the contents of each Pascal unit file. Fastgraph routines in FGBITMAP.TPU fg_clipmask fg_flipmask fg_imagebuf fg_revimage fg_clpimage fg_flpimage fg_imagesiz fg_revmask fg_drawmask fg_getblock fg_putblock fg_drwimage fg_getimage fg_putimage Fastgraph routines in FGGIF.TPU fg_makegif fg_showgif Fastgraph routines in FGMISC.TPU fg_button fg_intkey fg_mousepos fg_setcaps fg_capslock fg_kbinit fg_mouseptr fg_setnum fg_cursor fg_kbtest fg_mousespd fg_sound fg_getclock fg_measure fg_mousevis fg_sounds fg_getkey fg_memavail fg_music fg_suspend fg_getxjoy fg_mousebut fg_musicb fg_voice fg_getyjoy fg_mousecur fg_numlock fg_voices fg_hush fg_mousefin fg_playing fg_waitfor fg_hushnext fg_mouseini fg_quiet fg_waitkey fg_initjoy fg_mouselim fg_resume fg_intjoy fg_mousemov fg_scrlock Fastgraph routines in FGPCX.TPU fg_makepcx fg_pcxhead fg_pcxmode fg_showpcx Fastgraph routines in FGPR.TPU fg_dispfile fg_displayp fg_makespr fg_showspr fg_display fg_makeppr fg_showppr Fastgraph routines in FGSVGA.TPU fg_defpages fg_svgainit fg_svgaver fg_memory fg_svgastat Pascal versions of the routines listed in Appendix D are in the unit file FGWORLD.TPU. All other Fastgraph routines are in the FGMAIN.TPU unit file. As mentioned in Chapter 1, Pascal programs must include a uses statement listing all units referenced in the program. The FGMAIN unit is always required. Other unit files are needed when you call the Fastgraph functions they contain. Appendix F Integrating Fastgraph With Other Graphics Software 334 Fastgraph User's Guide Sometimes you may want to use Fastgraph with other graphics software, such as when converting an existing graphics application to Fastgraph. This appendix may clarify some points about doing this. First, let the other graphics software establish the video mode, then initialize Fastgraph for that mode by calling fg_setmode(-1). Passing -1 to fg_setmode does not physically change video modes but merely initializes Fastgraph's internal parameters for the current video mode. Second, if you're using the EGA/VGA/SVGA 16-color graphics modes (modes 13 to 18, 28, and 29), you'll probably need to explicitly define the value of the EGA/VGA Enable Set/Reset register (port address 03CE hex, index 01). Fastgraph's functions expect this register to have the value 0F hex; this allows Fastgraph take advantage of a more efficient variant available in EGA/VGA write mode 0. The default value for the Enable Set/Reset register is zero. After you've called fg_setmode(-1) and need to call a third party graphics function, set the Enable Set/Reset register to its default value by including the following statement just before calling the third party function: outport(0x03CE,0x0001); Borland C++, Turbo C/C++, or Power C outpw(0x03CE,0x0001); Microsoft C or QuickC OUT &h03CE,1 : OUT &h03CF,0 QuickBASIC or Visual Basic Just before you call the next Fastgraph function, restore the Enable Set/Reset register value with the following statement: outport(0x03CE,0x0F01); Borland C++, Turbo C/C++, or Power C outpw(0x03CE,0x0F01); Microsoft C or QuickC OUT &h03CE,1 : OUT &h03CF,15 QuickBASIC or Visual Basic Index 335 I n d e x 8253-5 programmable timer chip /M option 311 286 /P option 311 Active page 151, 152 /W option 311 Animation 238 Clipping 98 dynamic frame 244 Clock tick 300-302 dynamic page flipping 246 Clock tick interrupt 291, 293, page flipping 246 300 simple 238 Color 68 static frame 242 Color indices 90 static page flipping 246 Color number 70 summary 248 Color value 70 XOR 240 Compilation 5 ANSI.SYS 45 BASIC PDS 11 Assembly language 318 Borland C++ 8 Attribute 68, 132, 133 Borland Pascal 10 Available memory 304 Microsoft C 13 Background color 68-70 Microsoft C++ 13 BASIC PDS 11 Microsoft FORTRAN 14 Bit maps 190 Power C 23 CGA 195, 196, 203 QuickBASIC 16 EGA 198, 205 QuickC 18 filler bits 191 Turbo C 25 Hercules 198 Turbo C++ 25 MCGA 199 Turbo Pascal 27 memory requirements 209 Visual Basic 20 mode-independent 190 Visual C++ 22 mode-specific 194 Zortech C++ 28 PCjr 198 Compiler-specific Fastgraph retrieving 207 library 330 subscript order 191, 192, CONVERT 312, 313 202 /PPR switch 312 SVGA 198, 199 /SPR switch 312 Tandy 198 Convex shape 108 text modes 201 Coordinate conversion 64, 137, VGA 198, 199 138 Bit-mapped characters 145 Current color 70 Bit-mapped images 190 Cursor mask 273, 275 BitBlt 222 Dash pattern 104, 105 Blit 222 Delay units 301, 302 Block transfer routines 222 Display patterns 181 Borland C++ 3, 8 CGA 181, 182 Borland Pascal 3, 10 EGA 184 Byte boundary 223, 224 Hercules 184 CapsLock 262-264 MCGA 184 CGA palettes 70 PCjr 183 Character cells 32 SVGA 184 Character space 60, 128 Tandy 183 Characters VGA 184 bit-mapped 145 Dithering 114 hardware 129 Dithering matrix 114 software 139 256-color modes 119 Circles 109 alignment 120 Clearing the screen 98 CGA 115, 116 CLIP 311, 312 EGA 118 336 Fastgraph User's Guide Dithering matrix (cont.) fg_dash 104, 105, 123 Hercules 117 fg_dashrel 104, 123 PCjr 117 fg_dashrw 104, 123 SVGA 118 fg_dashw 104, 123 Tandy 117 fg_defcolor 91, 94, 120 VGA 118 fg_dispfile 180, 181, 188, EDITSPR 313 214 Ellipses 109 fg_display 212-214, 219 EMM386.EXE 162 fg_displayp 213, 214, 219 EMS 162 fg_draw 102, 123, 254 Expanded memory 162 fg_drawmap 145, 190, 192, Expanded Memory Manager 162 193, 194, 195, 207, Extended Fastgraph library 330 208, 209, 212, 215, Extended memory 162 218, 219, 230, 248, Fade 85, 86 275, 278 FASTGRAF.BI 6 fg_drawmask 216-219 FASTGRAF.H 6 fg_drawrel 102, 121, 123 Fastgraph 2 fg_drawrelx 102, 123 Fastgraph routines fg_drawrw 102, 123 fg_allocate 154, 155, fg_drawrxw 102, 123 157, 158, 160-162, fg_draww 102, 124 167-169, 222, 226, fg_drawx 102, 124 227, 304 fg_drawxw 102, 124 fg_alloccms 162, 163, fg_drect 114, 115, 118, 166, 167 119, 120, 124 fg_allocems 162, 163, 169 fg_drectw 115, 120, 124 fg_allocxms 162, 163, 169 fg_drwimage 145, 195-198, fg_automode 49, 50, 56, 200-204, 207, 209, 99, 109, 111, 256 212, 215, 217, 218, fg_bestmode 46, 50, 51, 219, 248, 278 53, 57, 121, 155, fg_ellipse 109, 124, 242 157, 158, 233 fg_ellipsef 109, 124 fg_box 112, 122 fg_ellipsew 109, 124 fg_boxdepth 112, 122 fg_ellipsfw 109, 124 fg_boxw 112, 122 fg_erase 98, 124, 168 fg_boxx 113, 114, 122 fg_fadein 250, 251, 258 fg_boxxw 113, 122 fg_fadeout 250, 258 fg_button 280, 281, 283, fg_fillpage 98, 124 322, 323 fg_flipmask 216, 217, 219 fg_capslock 263, 283 fg_flood 121, 124 fg_chgattr 132, 145 fg_floodw 121, 124 fg_chgtext 132, 146 fg_flpimage 203, 204, 207, fg_circle 109, 123 215, 217, 219 fg_circlef 109, 123 fg_fontsize 137, 146 fg_circlefw 109, 123 fg_freepage 155, 157, 158, fg_circlew 109, 123 162, 165, 169, 304 fg_clipmask 216, 217, 219 fg_getaddr 160, 169 fg_clpimage 203, 204, fg_getattr 133, 146 207, 215, 217, 219 fg_getblock 233, 234 fg_clprect 111, 123, 238, fg_getchar 133, 146 245, 246 fg_getclock 301, 303 fg_clprectw 111, 123 fg_getcolor 69, 70, 77, 94 fg_copypage 163, 164, fg_getdacs 86-88, 94, 306 166, 168, 169, 222, fg_getentry 166, 169 234 fg_gethpage 225, 234 fg_cursor 44, 57, 94, fg_getimage 133, 207, 209, 134, 226 210, 219, 233, 248 Index 337 Fastgraph routines (cont.) fg_mouseini 165, 267-269, fg_getindex 94 271, 284 fg_getkey 262, 265, 283 fg_mouselim 269, 270, 284 fg_getlines 47, 57 fg_mousemov 269, 270, 284 fg_getmap 207-210, 219, fg_mousepos 271, 272, 284 230, 248 fg_mouseptr 273, 277, 284 fg_getmaxx 61, 62, 64, fg_mousespd 269, 270, 284 111 fg_mousevis 269, 272, 284 fg_getmaxy 61, 62, 64, fg_move 101, 102, 105, 111 121, 125, 135, 178, fg_getmode 46, 57, 318 180, 193, 194, 208, fg_getpage 160, 169 210, 214, 230, 254 fg_getpixel 99, 124 fg_moverel 101, 102, 125 fg_getrgb 84-86, 94 fg_moverw 101, 125 fg_getvpage 160, 169 fg_movew 101, 125 fg_getworld 63, 64 fg_music 289-291, 293, fg_getxjoy 280-283 296, 322 fg_getxpos 102, 124 fg_musicb 293-296, 322 fg_getyjoy 280-283 fg_numlock 263, 284 fg_getypos 102, 124 fg_pagesize 161, 168, 170 fg_hush 291, 293, 294, fg_paint 121, 125, 254 296 fg_paintw 121, 125 fg_hushnext 291, 293, fg_palette 71-80, 82-84, 294, 296 89, 90, 94, 95, 201 fg_imagebuf 186, 187 fg_palettes 90, 95, 306 fg_imagesiz 209, 210, fg_pan 255-258, 306 219, 233 fg_panw 255, 256, 258 fg_initems 162, 163, 165, fg_pattern 181, 185, 188, 169 212, 213 fg_initjoy 165, 279-281, fg_pcxhead 174, 188 283 fg_pcxmode 174, 188 fg_initw 62, 64, 101, 140 fg_playing 291, 294, 296 fg_initxms 162, 165, 170 fg_point 99, 101, 125 fg_inside 109, 125 fg_pointw 99, 101, 125 fg_intjoy 281-283 fg_pointx 101, 125 fg_intkey 262, 263, 265, fg_pointxw 101, 125 281, 283, 294, 301 fg_polyfill 107-109, 125 fg_justify 133-135, 146 fg_polygon 105-107, 125 fg_kbinit 265, 266, 283 fg_polygonw 106, 125 fg_kbtest 265, 266, 283 fg_polyline 107-109, 125 fg_locate 129-131, 134, fg_polyoff 107 137, 146, 152, 159, fg_print 133-137, 146 210 fg_putblock 233, 234 fg_makegif 175, 176, 188, fg_putimage 203, 207, 215, 306 219, 233 fg_makepcx 172, 173, 175, fg_quiet 287-289, 296 176, 178, 188, 306 fg_rect 80, 84, 111, 112, fg_makeppr 180, 188 114, 125, 137-139, fg_makespr 178, 180, 188 152, 192, 196, 227, fg_maprgb 89, 94 238, 245 fg_measure 302, 303 fg_rectw 111, 125, 144 Fg_memavail 304, 307 fg_reset 45, 46, 57, 318 fg_memory 55, 57 fg_resize 164, 165, 170, fg_mousebut 271, 272, 283 257, 258 fg_mousecur 273, 274, 284 fg_restore 225, 227, 228, fg_mousefin 268, 284 233, 235, 245, 251 fg_restorew 225, 235 338 Fastgraph User's Guide Fastgraph routines (cont.) fg_showspr 178, 180, 181, fg_resume 295, 296 188 fg_revimage 203, 204, fg_sound 286-289, 291, 207, 215, 217, 220 292, 296 fg_revmask 216, 217, 220 fg_sounds 291, 292, 294, fg_save 225-228, 233, 235 296, 322 fg_savew 225, 235 fg_stall 301-303 fg_scrlock 263, 284 fg_suspend 295, 296 fg_scroll 252-254, 258 fg_svgainit 53-55, 57 fg_setangle 143, 146 fg_svgaver 55, 57 fg_setattr 68, 69, 95, fg_swchar 140-144, 146 98, 129, 130, 132, fg_swlength 144, 147 146, 152, 153, 156, fg_swtext 143, 144, 147 158 fg_tcdefine 231-233, 235 fg_setcaps 264, 284 fg_tcmask 231-233, 235 fg_setclip 98, 126, 203 fg_tcxfer 231-233, 235 fg_setclipw 98, 126 fg_testmode 45, 46, 51, fg_setcolor 44, 69-80, 53, 55, 57, 87, 152, 82, 83, 84, 95, 98, 155, 205, 225, 288 99, 118, 119, 129, fg_text 44, 129-134, 136, 132, 140, 146, 152, 137, 138, 140, 146, 153, 156, 158, 192, 147 239, 240, 241, 252, fg_transfer 228, 230-233, 253 235, 244-246, 251 fg_setdacs 86-88, 95, fg_version 5, 55, 318 306, 314 fg_voice 287-289, 291-293, fg_setentry 166, 168, 170 296 fg_setfunc 240, 305, 307 fg_voices 292-294, 297, fg_sethpage 225, 226, 322 235, 250, 252 fg_waitfor 85, 238, 244, fg_setlines 47, 57 246, 254, 256, 263, fg_setmode 44, 46, 53, 270, 289, 300-303 57, 70, 77, 83, 88, fg_waitkey 45, 262, 265, 90, 91, 98, 99, 101, 284 109, 111, 117, 118, fg_waitvr 306, 307 129, 130, 132, 140, fg_where 131, 147, 159 152, 159, 165, 166, fg_xalpha 64, 65, 138, 147 182, 183-185, 205, fg_xconvert 64, 65, 138, 260, 267, 279, 318, 139, 147 334 fg_xscreen 64, 65, 99 fg_setnum 264, 284 fg_xworld 64, 65, 102 fg_setpage 152, 170, 225 fg_yalpha 64, 65, 138, 147 fg_setratio 140, 142, 146 fg_yconvert 64, 65, 138, fg_setrgb 73, 76, 80, 82, 139, 147 83, 84, 86, 89, 94, fg_yscreen 64, 65, 99 95, 185, 201 fg_yworld 64, 65, 102 fg_setsize 140, 146 Fastgraph/Light 2 fg_setsizew 140, 146 Fastgraph/Light Video Driver 2, fg_setvpage 152, 161, 29 170, 246, 269, 306, FGDRIVER 29 307 /U option 29 fg_setworld 62-64, 140 Filler bits 191 fg_showgif 175, 176, 188, Fish tank animation demo 248 306 Flickering 306 fg_showpcx 172-175, 187, Foreground color 68, 69 188, 306 Full page transfer 222 fg_showppr 180, 188 Game port 279 Index 339 GetMem (TP procedure) 186, 233 vertical position 280 GIF file 175 Keyboard 260 creating 175 buffer 262, 301 displaying 175 extended codes 260 GrabRGB 181, 313, 314 handler 264 /D option 314 standard codes 260 output file format 314 state light 264 Graphics cursor 101 Lines Graphics modes 32, 35, 70 dashed 104 256-color 83 solid 102 CGA 35, 70, 72 Linking 5 EGA 37, 76, 78, 79 Logical pages 162 Hercules 36, 74, 75 creating 162 MCGA 38, 81 releasing 162 native EGA 37 Masking map 201, 215-218 native VGA 38 Memory conflicts PCjr 36, 73 logical pages 167 SVGA 40, 83 virtual pages 167 Tandy 73 Memory models 3 Tandy 1000 36 large 4 VGA 38, 81, 83 medium 4 XVGA 39 small 3 Hardware characters 129 Memory update function 305 graphics modes 133 Mickeys 269 height 137 Microsoft BASIC PDS 11 side effects 136 Microsoft C 3, 13 text modes 129 Microsoft C++ 3, 13 HERCFIX 314, 315 Microsoft FORTRAN 3, 14 Hidden page 151, 225 Microsoft Mouse 267 HIMEM.SYS 162 Microsoft QuickBASIC 3, 16 Hot spot 277 Microsoft QuickC 3, 18 Image array 201 Microsoft Visual Basic for DOS Image buffer 186 3, 20 Images 172 Microsoft Visual C++ 3, 22 clipped 203 Mode X 39 regular 195 Mouse 266 reversed 203 button status 271 reversed clipped 203 CGA Considerations 278 without transparent pixels cursor 269, 273 203 cursor mask 273, 275 INCLUDE environment variable 6 cursor visibility 269 Input devices 260 default cursor 275 INSTALL program 4 hot spot 277 /L option 5 initialize 267 Installation 4 limits 269 Interrupts 322 position 269, 271 INTRFACE.FOR 6 screen mask 273, 275 Joystick 279 screen updates 269 button status 280, 281, speed 269 322 SVGA 268 calibration 280 XVGA 268 characteristics 280 Mouse cursor 269, 273 horizontal position 280 graphics modes 275 initialize 279 hot spot 277 keyboard emulation 281 text modes 273 special considerations Mouse driver 266 283 Music 289 340 Fastgraph User's Guide Music (cont.) unfilled 112 asynchronous 293 Region fill 121 restarting 295 Register preservation 318 stopping 294 Resolution 32 suspending 295 Reverse video 132 synchronous 289 RGB color mapping 89 Music commands 289 Rubberband boxes 102, 113 Music string 289, 293 Scan codes 265 Musical notes 289 Screen dissolving 250 Naming conventions 5 Screen mask 273, 275 NumLock 262-264 Screen origin 255 Overscan 71 Screen space 60, 61 Packed pixel run file 176, 179 Scrolling 252 Packed pixel run map 180, 213 circular 252 Page flipping 246, 247, 306, end-off 252 307 increment 252 Palette 33 region 252 Palette number 73, 76, 78, 79, ScrollLock 262, 263 82 SETMEM (BASIC function) 161 Palette registers 73, 76, 78, Shadow 132 79, 81, 83, 90, 91 Sliding tone 287 Palette value 73, 76, 78, 79 SNAPSHOT 181, 310, 311, 313, Palettes 73, 76, 78, 79, 81, 314 83 error tone 310 Panning 164, 257, 306 image files 310 PC Paintbrush 172 success tone 310 PCOPTION environment variable Software characters 139 6 alternate font 139, 140, PCX file 172 143 creating 172 angle 143 displaying 172 aspect ratio 140 video mode compatibility font change operator (\) 174 141 PCXHEAD 315 primary font 139, 140 Periodic noise 288 size 140 Physical pages 150 string length 144 Pixel bleeding 279 subscript operator (\v) Pixel run 177 142 Pixel run file 176, 178, 180, superscript operator (\^) 181, 214 142 Pixel run map 177, 181, 212 underline operator (_) 142 Pixels 32 Sound 286 Points 99 asynchronous 290 Polygon disk accesses during 291 filled 107, 108 duration 286 unfilled 105-107 frequency 286 vertex offsets 107 PCjr 286 Power C 3, 23 stopping 294 PPR file 176, 179 synchronous 286 Put_string 131 Tandy 286 QuickBASIC 3, 16 volume 286 QuickC 3, 18 Sound effects 286-288 READ.ME file 5 Splitter cable 279 Real-time operations 300 SPR file 176 Rectangles Standard color set 70 dithered 114 Standard pixel run file 176 solid 111 Strlen 131 Index 341 Stroke characters 139 mode 23 40 SuperVGA 51 mode 24 40 SVGA 51 mode 25 40 chipset 52 mode 26 40 dual banks 224 mode 27 41 initialization 53-55 mode 28 41 kernel 40, 52-56 mode 29 41 kernel version 54, 55 mode X 39 monitor compatibility 56 summary 32 problematic cards 56 Video page resizing 257 supported chipsets 52, 53 Video pages 33, 150 VESA compatibility 52, 53 active 151, 152 video memory present 55 hidden 151, 225 Texas Instruments SN76496A logical 162 sound chip 286 physical 150 Text cursor 44, 129, 159 preserving 160, 166 Text modes 32, 33, 68 resizing 164 43 lines 47 segment address 160 50 lines 47 virtual 150, 154 color 68 visual 151, 152 monochrome 69 Video subsystem 33 TI sound chip 286 Virtual colors 90, 91 Transparency 190, 195, 197, Virtual pages 150 198, 200, 201, 203, creating 154 204, 212, 215, 218, heap requirements 161 231, 232, 233 page flipping 161 Turbo C 3, 25 releasing 155 Turbo C++ 3, 25 writing to unallocated 162 Turbo Pascal 3, 27 Visual Basic 3, 20 Vector characters 139 Visual C++ 3, 22 Vertical retrace 306 Visual effects 251 VESA 52, 53 Visual page 151, 152 Video DAC registers 81-84, 86, Warbling 287 90, 306 White noise 288 EGA modes 87 World space 60, 62 Video modes 32 XMS 162 mode 00 34 XOR boxes 113 mode 01 34 XOR lines 102 mode 02 34 XOR pixels 101 mode 03 34 Zortech C++ 3, 28 mode 04 35 mode 05 35 mode 06 36 mode 07 35 mode 09 36 mode 11 36 mode 12 37 mode 13 37 mode 14 37 mode 15 37 mode 16 38 mode 17 38 mode 18 38 mode 19 39 mode 20 39 mode 21 39 mode 22 39